namespace TripleA.Core.Database
{
    using System;
    using System.Data;

    public interface IAdhocCommandBase : IDisposable
    {
        /// <summary>
        /// Prepares this command on the server - improves performance if executed
        /// many times as it just swaps the parameters values as they change. Requires
        /// parameters to be explicitly defined (type and size)
        /// </summary>
        /// <returns></returns>
        AdhocCommandBase PrepareOnServer();

        /// <summary>
        /// Sets the sql statement to execute
        /// </summary>
        /// <param name="statement"></param>
        /// <param name="args"></param>
        /// <returns></returns>
        AdhocCommandBase WithSql(string statement, params object[] args);

        /// <summary>
        /// Sets the sql statement to execute from the <see cref="ISqlStatement"/>
        /// fluent interface. Any parameters set on the SqlStatement will 
        /// replace any existing set of parameters.
        /// </summary>
        /// <param name="sql"></param>
        /// <returns></returns>
        AdhocCommandBase WithSql(ISqlStatement sql);

        /// <summary>
        /// Adds parameter(s) to the command. This is recommended when the command
        /// takes external values as part of the command sql as there are much
        /// lower security risks than inline parameter values using strings directly
        /// </summary>
        /// <param name="parameters"></param>
        /// <returns></returns>
        AdhocCommandBase AddParameters(params IDataParameter[] parameters);

        /// <summary>
        /// Creates a database command object to execute
        /// </summary>
        /// <returns></returns>
        IDbCommand Build();

        /// <summary>
        /// Creates the command and executes it to return a reader with 
        /// firehose (r/o, f/o) access to the data returned
        /// </summary>
        /// <returns></returns>
        IDataReader ExecuteReader();

        /// <summary>
        /// Creates the command and executes it 
        /// </summary>
        int ExecuteNonQuery();

        /// <summary>
        /// Creates the command and executes it and returns the first 
        /// column of the first row in the resultset
        /// </summary>
        object ExecuteScalar();

        /// <summary>
        /// This will set the value of a parameter on an existing command object.
        /// </summary>
        /// <param name="paramName"></param>
        /// <param name="value"></param>
        /// <returns></returns>
        AdhocCommandBase SetParameterValue(string paramName, object value);
    }
}